DataformをAPIで実行してみた

DataformをAPIで実行してみた

#Dataform
#Google Cloud (GCP)
#Google BigQuery
根本夏瑠

根本夏瑠

facebook logohatena logotwitter logo
Clock Icon2024.04.22

データアナリティクス事業本部の根本です。以前のブログでDataformを動作検証してみたのですが、今回はDataformをAPIで実行してみる検証を行いました。主にDataformのAPIを用いてワークフローが実行できるか、タグ指定での実行ができるか、などを検証しました。

この記事の対象者

  • Dataform APIを叩いてみたいひと

事前準備

  • DataformのAPIが有効化されていること
  • Dataformのリポジトリ、ワークスペースが作成済み、何かしらのワークスペースがあること
  • gcloudコマンドを実行できる環境があること

APIを叩いてみる！

4種類の検証をしてみました。
1. リポジトリ一覧をAPIで取得
2. ワークスペース指定でのワークフロー実行
3. GitのブランチとDataformのタグ指定でのワークフロー実行
4. ワークフロー構成で作成したワークフローをDataformのタグ指定でワークフロー実行
それでは順番に検証していきます。

まずはリポジトリ一覧をAPIで取得してみる

まずはDataform APIを叩く練習として、Dataformのリポジトリ一覧をAPIで取得してみます。
リポジトリ一覧取得APIのリファレンス

GET https://dataform.googleapis.com/v1beta1/{parent=projects/*/locations/*}/repositories`

叩くAPIは上記です。プロジェクト名やリージョンは適切な値に置き換えます。
それではcurlコマンドで実行します。

% curl https://dataform.googleapis.com/v1beta1/projects/test-project/locations/asia-northeast1/repositories/  \
--header "Authorization: Bearer $(gcloud auth print-access-token)"

- Authrization: Bearer $(gcloud auth print-access-token)
APIの認証は、gcloudコマンドで設定しているGoogle Cloudアカウントの認証情報から生成したアクセストークンを用いて認証しています。 レスポンスは以下でした。

{
  "repositories": [
    {
      "name": "projects/test-project/locations/asia-northeast1/repositories/dataform-test",
      "createTime": "2024-04-18T04:44:11.683704618Z"
    }
  ]
}

Dataformのリポジトリ一覧画面で見た内容と一致していました。
リポジトリ一覧をAPIで取得することができているようです。

いよいよワークフローを実行してみる

APIのリファレンスを見ると、どうやらコンパイル→ワークフロー実行の流れになっている様子。
なのでまずはコンパイルをします。コンパイル実行APIのリファレンス
叩くAPIは以下となります。

POST https://dataform.googleapis.com/v1beta1/{parent=projects/*/locations/*/repositories/*}/compilationResults

コマンドは以下になります。

curl -X POST https://dataform.googleapis.com/v1beta1/projects/test-project/locations/asia-northeast1/repositories/dataform-test/compilationResults \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Content-Type: application/json" \
  --data '{"workspace":"projects/test-project/locations/asia-northeast1/repositories/dataform-test/workspaces/test-workspace-1"}'

プロジェクト名、リージョンは適切な値に置き換えます。
リクエストボディ(--data)の部分に関して簡単に解説します。
リファレンスによるとコンパイル対象としては以下が指定できます。

key 概要
gitCommitish GitコミットID、ブランチ名、Gitタグ名
workspace ワークスペース名
releaseConfig リリース構成の名称(リリースとスケジュールで設定した名称)

上記のうち、どれかを指定してコンパイルします。
また上記のコンパイル対象以外にコンパイル設定も追加できます。
まずはworkspace(ワークスペース名)を指定してコンパイルしました。実行対象のワークスペース名はtest-workspace-1という名前で設定しています。
コマンドを実行して、以下のレスポンスが帰ってきました。

{
  "name": "projects/test-project/locations/asia-northeast1/repositories/dataform-test/compilationResults/b8de66ab-fe33-4ea2-83af-4077b17a2f88",
  "workspace": "projects/****project-id****/locations/asia-northeast1/repositories/dataform-test/workspaces/test-workspace-1",
  "codeCompilationConfig": {
    "defaultDatabase": "test-project",
    "defaultSchema": "test_dataform",
    "assertionSchema": "dataform_assertions",
    "defaultLocation": "asia-northeast1"
  },
  "dataformCoreVersion": "2.8.3"
}

無事成功していました。 レスポンスのnameの内容を、ワークフロー実行時に使用します。
それではワークフローを実行してみます。ワークフロー実行APIのリファレンス
ワークフロー実行APIは以下となります。

POST https://dataform.googleapis.com/v1beta1/{parent=projects/*/locations/*/repositories/*}/workflowInvocations

--dataにて、コンパイル結果のnameを設定して実行します。

curl "https://dataform.googleapis.com/v1beta1/projects/test-project/locations/asia-northeast1/repositories/dataform-test/workflowInvocations" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header 'Content-Type: application/json' \
  --data '{"compilationResult":"projects/test-project/locations/asia-northeast1/repositories/dataform-test/compilationResults/b8de66ab-fe33-4ea2-83af-4077b17a2f88"}'

実行に成功したようで以下のレスポンスが返ってきました。

{
  "name": "projects/test-project/locations/asia-northeast1/repositories/dataform-test/workflowInvocations/1713770749-67d1c962-c74a-4036-975e-c13843ef8481",
  "compilationResult": "projects/****project-id****/locations/asia-northeast1/repositories/dataform-test/compilationResults/b8de66ab-fe33-4ea2-83af-4077b17a2f88",
  "state": "RUNNING",
  "invocationTiming": {
    "startTime": "2024-04-22T07:25:49.739354Z"
  },
  "resolvedCompilationResult": "projects/****project-id****/locations/asia-northeast1/repositories/dataform-test/compilationResults/b8de66ab-fe33-4ea2-83af-4077b17a2f88"
}

state(状態)という項目で、実行の状態を把握することができます。
stateが返却する値はリファレンスより以下のどれかになります。

state 概要
STATE_UNSPECIFIED 初期値。使用されることはない
RUNNING ワークフローが実行中
SUCCEEDED 成功
CANCELLED キャンセル
FAILED 失敗
CANCELING キャンセル中

確認したところワークフローを実行するAPIは非同期処理となっており、レスポンスはワークフローの状態を返却するだけでした。よって、ワークフローの処理完了やエラーを検知するには呼び出し元システムでポーリングして状態把握してあげる必要がありそうです。
それでは、Dataformのコンソールからワークフローの実行履歴を確認してみます。
実行履歴を見ると
ソースタイプ：ワークスペース
ソース：test-workspace-1 となっており、API実行時にワークスペース(test-workspace-1)をソースにワークフローを実行していたので期待通りの結果でした。

コンパイル処理→ワークフロー実行のイメージは以下となります。　　

Gitのブランチとタグを指定してワークフローを実行してみる

Gitのブランチ名を指定してコンパイルして、Dataformのタグ指定でワークフローを実行してみます。
以下の設定値をもとにAPIを叩いてみます。

ブランチ名 タグ名
main first_view

※タグ名はSQLXのconfigで以下のような実装で設定します。

config {
  tags: ["first_view"]
}

今回はfirst_viewというタグ名を設定したSQLXファイルをmainブランチにpushした状態でコンパイルをします。

curl -X POST https://dataform.googleapis.com/v1beta1/projects/test-project/locations/asia-northeast1/repositories/dataform-test/compilationResults \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Content-Type: application/json" \
  --data '{"gitCommitish":"main"}'

--dataにて、gitCommitish:mainでmainブランチを指定します。

{
  "name": "projects/test-project/locations/asia-northeast1/repositories/dataform-test/compilationResults/291ee39d-6495-4f72-8b90-d0449ad3f2d2",
  "gitCommitish": "main",
  "codeCompilationConfig": {
    "defaultDatabase": "test-project",
    "defaultSchema": "test_dataform",
    "assertionSchema": "dataform_assertions",
    "defaultLocation": "asia-northeast1"
  },
  "dataformCoreVersion": "2.8.3",
  "resolvedGitCommitSha": "dbe4ce1c269728abe922f3afc5db9539790c1e26"
}

問題なくコンパイルされたようです。それではnameの値をもとにワークフローの呼び出しをしてみます。

curl "https://dataform.googleapis.com/v1beta1/projects/test-project/locations/asia-northeast1/repositories/dataform-test/workflowInvocations" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header 'Content-Type: application/json' \
  --data '{"compilationResult":"projects/test-project/locations/asia-northeast1/repositories/dataform-test/compilationResults/a8880167-bcde-4141-b9e7-513971a2c2f0", "invocationConfig":{"includedTags":["first_view"]}}'

--dataの"invocationConfig":{"includedTags":"first_view"}：こちらでDataformのタグ名を指定しています。
レスポンスは以下でした。

{
  "name": "projects/test-project/locations/asia-northeast1/repositories/dataform-test/workflowInvocations/1713773465-1cc6860f-97a9-410e-a4ff-ebfe687477c8",
  "compilationResult": "projects/****project-id****/locations/asia-northeast1/repositories/dataform-test/compilationResults/a8880167-bcde-4141-b9e7-513971a2c2f0",
  "invocationConfig": {
    "includedTags": [
      "first_view"
    ]
  },
  "state": "RUNNING",
  "invocationTiming": {
    "startTime": "2024-04-22T08:11:06.008199Z"
  },
  "resolvedCompilationResult": "projects/****project-id****/locations/asia-northeast1/repositories/dataform-test/compilationResults/a8880167-bcde-4141-b9e7-513971a2c2f0"
}

上記より"state": "RUNNING"が返却されているのでタグ指定でのワークフロー実行ができており、実行中(RUNNING)となっているようです。
画面で実行されているかどうか確認してみます。
実行が完了していました。画面の表示内容より、以下の状態で実行されたことが確認できました。

ソースタイプ ソース 目次
GitCommitish main タグ:first_view

こちらはコンパイル・ワークフロー時に指定した項目ですので、期待値通りの動作と考えます。

ワークフロー構成で作成したワークフローをタグ指定で呼び出してみる

最後に、[ワークフロー構成]で作成してあるワークフローに対して、タグ指定で呼び出しをしてみます。 このワークフロー構成は[ALL ACTIONS]指定で作成をしています。

nemoto.natsuru@hl01488 devio % curl "https://dataform.googleapis.com/v1beta1/projects/test-project/locations/asia-northeast1/repositories/dataform-test/workflowInvocations" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header 'Content-Type: application/json' \
  --data '{"workflowConfig":"projects/test-project/locations/asia-northeast1/repositories/dataform-test/workflowConfigs/production-workflow", "invocationConfig":{"includedTags":["first_view"],"transitiveDependenciesIncluded":"false"}}'
{
  "error": {
    "code": 400,
    "message": "com.google.apps.framework.request.BadRequestException: Invocation config must not be set when source is workflow config",
    "status": "INVALID_ARGUMENT"
  }
}

呼び出せませんでした。

"message": "com.google.apps.framework.request.BadRequestException: Invocation config must not be set when source is workflow config"

エラーメッセージを見ると、ワークフローを実行単位に指定した場合、タグ指定などの呼び出し設定(invocationConfig)を設定することはできないようです。

終わりに

今回はCLIでDataform APIを叩いてみて、動作を確認してみました。
APIを用いてDataformを呼び出せることが確認できたので、Cloud FunctionsやWorkflowsに組み込んで 実運用に持っていく、ということが可能だと思いました。Dataformの[リリースとスケジュール]から設定できる スケジュール起動以外に、Cloud FunctionsやWorkflowsから起動できることで、より活用の幅が広がるのではないかなと思います。 バケットへの保存イベントトリガー→Cloud Functionsの処理→Dataform処理 というようなイベントドリブンの処理にもDataformを組み込めると思います。 この記事が誰かの役に立てば嬉しいです。それでは。

参考

gcloud auth print-access-token
リポジトリ一覧取得API
コンパイル実行APIのリファレンス
ワークフロー実行APIのリファレンス

Share this article

facebook logohatena logotwitter logo

関連記事

DataformをGCEインスタンス上のGitリポジトリとHTTPSで連携してみる

DataformをGCEインスタンス上のGitリポジトリとHTTPSで連携してみる

User avatar
根本夏瑠
2024.10.19
DataformをGCEインスタンス上のGitリポジトリとSSHで連携してみる

DataformをGCEインスタンス上のGitリポジトリとSSHで連携してみる

User avatar
根本夏瑠
2024.10.17
Dataformのコンパイル時にDataformがGitリポジトリと接続できない場合の動作を観察してみた

Dataformのコンパイル時にDataformがGitリポジトリと接続できない場合の動作を観察してみた

User avatar
根本夏瑠
2024.10.10
Dataformのコンパイル済みSQLをDataform CLIで作成してSQLをファイルに抽出するスクリプトを作ってみた

Dataformのコンパイル済みSQLをDataform CLIで作成してSQLをファイルに抽出するスクリプトを作ってみた

User avatar
根本夏瑠
2024.10.03
Classmethod's white logo
Facebook's logo
X's logo
YouTube's logo

© Classmethod, Inc. All rights reserved.